Skip to main content

Ficha técnica

Escopos necessários​

O token para consumir a API de Recebíveis do BTG Pay deve ser gerado usando o Authorization Code.

O escopo openid é obrigatório. Ele permite consultar o perfil do usuário BTG com acesso à conta.

É necessário incluir o seguinte escopo:

EscopoDescrição
brn:btg:empresas:acquirer:dashboard.receivable-units.readonlyPermite a consulta de unidades recebíveis do cliente

Recebíveis — Visão Geral da API

A API de Recebíveis do BTG Pay permite que aplicativos parceiros consultem, em nome do cliente, as unidades recebíveis geradas por essas vendas. Esta documentação apresenta os principais fluxos disponíveis e como utilizá-los para montar o dashboard do parceiro.

Todos os recursos são somente leitura e recebem no path o companyId, que é o CNPJ da empresa cujos dados serão consultados. Os fluxos se organizam em torno do conceito cetral:

  • Unidade recebível — o valor líquido a ser liquidado em uma data futura, agrupado por bandeira e modalidade de venda.

Os valores monetários são representados por objetos com os campos currency (moeda, ex.: BRL) e value (valor decimal como string, com duas casas decimais — ex.: "150.75").

Fluxo de Recebíveis​

Cada venda dá origem a uma ou mais unidades recebíveis, que representam o valor líquido a ser liquidado em uma data futura. O fluxo de recebíveis permite ao parceiro montar a agenda de recebimentos do cliente.

Listagem de Unidades Recebíveis​

A listagem de unidades recebíveis retorna, para cada unidade, a data de pagamento, a bandeira do cartão, a modalidade da venda e o valor líquido a receber. Use esta consulta para exibir a agenda de recebíveis e para conciliação financeira.

A listagem aceita filtros por intervalo de datas (startDate e endDate), por bandeira (cardBrand), por modalidade (saleType) e por identificador de unidade (unitId, no formato UUID). Assim como a listagem de vendas, a resposta é paginada por cursor.

Requisição — GET /{companyId}/acquirer/receivable-units?startDate=2026-07-01&endDate=2026-08-31&pageSize=20

Resposta — 200 OK

{
  "_links": {
    "prev": null,
    "next": null
  },
  "data": [
    {
      "id": "b2c3d4e5-6f70-4a1b-8c9d-0e1f2a3b4c5d",
      "dueDate": "2026-08-09",
      "cardBrand": "visa",
      "saleType": "credit_card",
      "balance": { "currency": "BRL", "value": "146.20" }
    }
  ]
}

O campo dueDate é a data de pagamento da unidade recebível (formato yyyy-MM-dd) e o campo balance é o valor líquido a receber, representado como objeto { currency, value }.

Paginação​

As listagens de vendas e de unidades recebíveis usam paginação por cursor. Cada resposta traz um objeto _links com os cursores prev e next. Para buscar a próxima página, repita a requisição informando, no parâmetro cursor, o valor retornado em _links.next. O cursor é opaco e deve ser tratado como um identificador único da posição do último item visto na página atual. O tamanho da página é controlado pelo parâmetro pageSize.